services/cms/src/services/backend/ai-suggestions.ts (1)

10-15: Add a brief doc comment for this exported API helper.

Line 10 introduces a public function without a minimal intent/contract description.

♻️ Proposed change

+/**
+ * Requests AI-generated paragraph suggestions for a single paragraph action.
+ */
 export async function requestParagraphSuggestions(
   payload: ParagraphSuggestionRequest,
 ): Promise<ParagraphSuggestionResponse> {
   const response = await cmsClient.post("/ai-suggestions/paragraph", payload)
   return validateResponse(response, isParagraphSuggestionResponse)
 }

As per coding guidelines, "Require consistent, minimal function documentation... Public interfaces should have clearer and more comprehensive documentation."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/services/backend/ai-suggestions.ts` around lines 10 - 15,
Add a minimal doc comment above the exported function
requestParagraphSuggestions describing its purpose, expected input and output
contract: state that it sends a ParagraphSuggestionRequest to the
"/ai-suggestions/paragraph" endpoint, returns a validated
ParagraphSuggestionResponse (via validateResponse and
isParagraphSuggestionResponse), and note any errors it may throw (e.g.,
network/validation errors). Keep the comment concise (one to three lines) and
place it immediately above the requestParagraphSuggestions declaration.

services/cms/src/utils/Gutenberg/ai/registry.ts (1)

3-3: categories registry appears unused.

The categories Map and registerAbilityCategory function are defined but abilities.ts doesn't register any categories. If this is scaffolding for future use, consider adding a brief comment to clarify intent, or remove if not needed.

Also applies to: 6-9

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/utils/Gutenberg/ai/registry.ts` at line 3, The categories
Map (categories) and registerAbilityCategory function are defined but never used
by abilities.ts; either remove the unused registry or document it as intentional
scaffolding: if keeping, add a concise comment above const categories and
export/register code noting it's reserved for future ability grouping and
reference registerAbilityCategory and AbilityCategory so maintainers know why
it's present; if removing, delete the categories declaration and
registerAbilityCategory to avoid dead code and update any related exports in the
module.

services/headless-lms/chatbot/src/cms_ai_suggestion.rs (1)

17-17: Unused import.

BackendError is imported but not used in this file.

Suggested fix

-use headless_lms_utils::{ApplicationConfiguration, prelude::BackendError};
+use headless_lms_utils::ApplicationConfiguration;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/headless-lms/chatbot/src/cms_ai_suggestion.rs` at line 17, The
import BackendError in the use statement
(headless_lms_utils::{ApplicationConfiguration, prelude::BackendError}) is
unused; remove BackendError from that use declaration or, if you intended to
handle errors here, reference BackendError where appropriate (e.g., in function
signatures or error handling in functions like suggest_from_cms_ai). Update the
use line to only import ApplicationConfiguration or add the necessary
BackendError usage to avoid the unused-import lint.

services/cms/src/utils/Gutenberg/ai/abilities.ts (1)

128-132: Prefer for...of over forEach when not using return values.

Static analysis flagged that forEach callbacks shouldn't return values (even implicitly). Using for...of is cleaner here.

Suggested fix

 export function registerEditorAiAbilities(): void {
   registerAbility(fixSpellingAbility)
-  allPlaceholderAbilities.forEach((ability) => registerAbility(ability))
+  for (const ability of allPlaceholderAbilities) {
+    registerAbility(ability)
+  }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/utils/Gutenberg/ai/abilities.ts` around lines 128 - 132, The
function registerEditorAiAbilities uses allPlaceholderAbilities.forEach(...)
which static analysis flags; replace the forEach call with an explicit for...of
loop to iterate over allPlaceholderAbilities and call registerAbility(ability)
for each item (i.e., in registerEditorAiAbilities iterate: for (const ability of
allPlaceholderAbilities) { registerAbility(ability) }) to avoid the forEach
callback return-value issue and make intent clearer.

services/headless-lms/server/src/controllers/cms/ai_suggestions.rs (1)

8-12: setting_type is currently a no-op in the request contract.

ParagraphSuggestionMeta.setting_type is accepted, but not forwarded into CmsParagraphSuggestionInput (only tone and language are passed). Either wire it through end-to-end or remove it for now to avoid a misleading API field.

Also applies to: 81-86

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/headless-lms/server/src/controllers/cms/ai_suggestions.rs` around
lines 8 - 12, ParagraphSuggestionMeta currently exposes setting_type but the
controller does not forward it into CmsParagraphSuggestionInput (only tone and
language are mapped); either propagate setting_type through the mapping and into
CmsParagraphSuggestionInput and any downstream types/handlers that consume it
(ensure field names and types align), or remove setting_type from
ParagraphSuggestionMeta to avoid a no-op API field; update any
serializers/deserializers and unit tests that reference ParagraphSuggestionMeta
or CmsParagraphSuggestionInput to reflect the chosen change.

services/cms/src/utils/Gutenberg/withParagraphAiToolbarAction.tsx (2)

145-147: Replace hardcoded color literals with theme tokens.

This component currently mixes hardcoded colors/fallbacks (#ddd, white, rgba(...)). Please switch these to shared theme values for consistency.

As per coding guidelines: If a component uses colors, use colors from the theme if possible.

Also applies to: 304-307, 319-319

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/utils/Gutenberg/withParagraphAiToolbarAction.tsx` around
lines 145 - 147, The component withParagraphAiToolbarAction is using hardcoded
color literals (e.g. "#ddd", "white", "rgba(...)") in its styled rules (see uses
withSubmenu/hasSubmenu for border-right and other styles around the toolbar
button, submenu and tooltip); replace those literals with the shared theme
tokens or CSS variables (e.g. theme colors or existing --wp-admin-* vars) by
referencing the theme object or CSS vars used elsewhere in the codebase, update
the styles in the styled wrapper and any button/submenu/tooltip style blocks
(the rules around hasSubmenu, the toolbar button styles, and submenu/tooltip
blocks) to use the appropriate theme tokens for border, background and
text/overlay colors, and ensure fallbacks use theme tokens rather than raw
hex/rgba values.

---

35-37: Define a narrow interface for the block props instead of any.

The component accesses props.name, props.attributes.content, and props.setAttributes. A typed interface would catch contract issues here without overhead, e.g.:

interface ParagraphBlockProps {
  name: string
  attributes: { content?: string }
  setAttributes: (attrs: Record<string, any>) => void
  // ... other BlockEdit props for spreading

Note: WordPress's createHigherOrderComponent doesn't export a standard BlockEdit props type, so you'd need to define this locally or derive it from block registration.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/utils/Gutenberg/withParagraphAiToolbarAction.tsx` around
lines 35 - 37, Replace the overly broad any on ParagraphWithAiToolbar props with
a narrow local interface (e.g., ParagraphBlockProps) that includes at least
name: string, attributes: { content?: string }, and setAttributes: (attrs:
Record<string, any>) => void; update the component signature to use that
interface and keep the rest of the incoming props via a spread type or index
signature to preserve other BlockEdit fields so usages of props.name,
props.attributes.content, and props.setAttributes are type-checked.

services/cms/src/utils/Gutenberg/withParagraphAiToolbarAction.tsx (1)

422-427: Remove the empty object comment artifact.

Line 423 contains an empty object {} that appears to be a leftover artifact. This produces no output but adds noise.

🧹 Proposed cleanup

           >
-            {}
             <div
               dangerouslySetInnerHTML={{ __html: suggestionPreviewHtml || originalPreviewHtml }}
             />

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/cms/src/utils/Gutenberg/withParagraphAiToolbarAction.tsx` around
lines 422 - 427, Remove the stray empty object JSX artifact `{}` inside the
render block near the div that uses dangerouslySetInnerHTML (the element
referencing suggestionPreviewHtml || originalPreviewHtml) in
withParagraphAiToolbarAction.tsx; simply delete the `{}` so the JSX contains
only the surrounding elements and the <div dangerouslySetInnerHTML={{ __html:
suggestionPreviewHtml || originalPreviewHtml }} /> to eliminate the noise.

services/headless-lms/chatbot/src/cms_ai_suggestion.rs (1)

70-77: Consider using the is_html flag.

The is_html field is extracted but not used. If this is intentional (e.g., for future use or logging), consider adding a brief comment explaining why. Alternatively, if the LLM should handle HTML vs plain text differently, you could incorporate this into the prompt construction.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@services/headless-lms/chatbot/src/cms_ai_suggestion.rs` around lines 70 - 77,
The destructured field is_html from CmsParagraphSuggestionInput is extracted but
never used; either incorporate it into the prompt or explicitly document why
it’s ignored. Update the code around the CmsParagraphSuggestionInput
destructuring (and any prompt builder like the function that creates the LLM
prompt for paragraph suggestions) to branch on is_html — e.g., adjust prompt
text or mark content as HTML vs plain text so the LLM handles formatting
correctly — or if omission is intentional, add a short inline comment next to
the is_html binding explaining it’s intentionally unused for now (or add a TODO
referencing future HTML handling).